docs: update CLI and helm reference for v2.40.0 - #404

Preview deployment for your docs. Learn more about Mintlify Previews.

Claude encountered an error after 3m 34s —— View job

Doc quality review

Reviewed all 94 changed files at 55bc449. The bulk of the diff — kosli_get_snapshot.md, kosli_diff_snapshots.md, kosli_log_environment.md, kosli_list_*, and the live-docs example links — is regenerated sample data (timestamps, fingerprints, commit SHAs, snapshot indices) with no structural change; not itemised.

The substantive upstream changes are: the --config-file default moving from kosli to $HOME/.kosli.yml, the rewritten .kosli_ignore paragraph, the new --jira-trailer flag, the 1 MB JSON payload note, new S3 object-key validation, and new --digests-source acr guidance. Two of those contradict hand-authored pages.

Critical — hand-authored pages now contradict the v2.40.0 CLI

kosli config and every flag table in this PR now say the config file is read from $HOME/.kosli.yml (or --config-file / KOSLI_CONFIG_FILE) and "never implicitly from the current directory". Two hand-authored pages still tell readers the opposite. A customer with ./kosli.yaml next to their pipeline loses their org and API token silently on upgrade, and both pages tell them that setup is supported.

1. faq/faq.md:56

--config-file defaults to kosli, so if you name your file kosli.<yaml|toml|json> and the file is in the same location as where you run Kosli commands from, you can skip the --config-file altogether.

Both halves are now wrong: the default is $HOME/.kosli.yml, and a file in the working directory is never picked up. Replace with the new default path and note that a project-local file must be named explicitly with --config-file or KOSLI_CONFIG_FILE. Fix this →

2. getting_started/install.md:168

By default, the CLI looks for a config file called kosli.<yaml/yml/json/toml>

Same defect, on the page the rest of the site links to for flag configuration (/getting_started/install#assigning-flags-via-config-files is referenced from administration/authentication/api_authentication_methods.md:28 and getting_started/flows.md:10). While here, the precedence list at install.md:141-145 should mention KOSLI_CONFIG_FILE, which kosli_config.md now documents as an alternative to the flag. Fix this →

Improvement

3. changelog/index.mdx — no v2.40.0 entry

The changelog stops at v2.39.2. The config-file change is the kind a reader needs told explicitly rather than discovered from a flag table: an existing ./kosli.yaml stops being honoured. Worth an entry under Changes calling out the new default and the end of implicit current-directory lookup, alongside --jira-trailer (new feature) and the 1 MB --user-data / --attestation-data limit. If .mintlify/workflows/update-changelog.md generates this from the release tag, make sure it runs for v2.40.0 and doesn't bury the config-file change as a help-text tweak.

Upstream — does not block this merge

These are faithful copies of the release binary's output. A hand-edit here is deleted by the next update-cli-docs.yml run, so the fix belongs in kosli-dev/cli.

4. Three empty accordions and fragment titles on kosli attest jira — client_reference/kosli_attest_jira.md:247-261

The new --jira-trailer example's comment is a four-line comment block, and the docs generator starts a new <Accordion> at each comment line. The published page renders four accordions, three with an empty shell block, and titles that read as broken sentences: "confines scanning to the trailer value — useful when project keys collide with", "patterns like CVE identifiers; write the issue key alone (e.g. 'Jira: CVE-42'),", "not embedded in a longer hyphenated string ('Jira: CVE-2026-41284' is still filtered)". The last one is the accordion that actually holds the command.

Fix in kosli-dev/cli → cmd/kosli/attestJira.go: collapse the example's comment to a single line (the surrounding long description already carries the CVE-collision explanation), or keep only the first line as the title. Every other example in the file uses a one-line comment.

5. kosli snapshot s3 contradicts itself on include/exclude precedence — client_reference/kosli_snapshot_s3.md:24 vs :39-40

New prose: "when --include or --include-regex is set, exclude filters are ignored, so narrow the include filter instead." The flag table on the same page: "Cannot be used together with --include or --include-regex." A reader cannot tell whether passing both is silently ignored or rejected — and the answer decides whether the suggested workaround is even usable. Reconcile in kosli-dev/cli → cmd/kosli/snapshotS3.go.

6. .kosli_ignore advice points at a flag kosli snapshot paths doesn't have — client_reference/kosli_snapshot_paths.md:28-29

The shared paragraph says "Excluding the file with --exclude …" and "move its entries to --exclude and delete it", but kosli snapshot paths has no --exclude flag — its only flags are --dry-run, --help, --paths-file, --watch, and exclusions are the per-artifact exclude: key in the paths spec (shown at :37). kosli snapshot path (singular) does have -x, --exclude, so only the plural form is wrong. Either use the two-sentence variant here (as kosli snapshot azure and kosli snapshot s3 already do) or word it in terms of the spec file, in kosli-dev/cli → cmd/kosli/snapshotPaths.go.

7. Two unrelated paragraphs merge into one on kosli snapshot azure — client_reference/kosli_snapshot_azure.md:29-30

The new --dry-run sentence has no blank line after it, so Markdown renders "--dry-run suppresses only the request to Kosli. Azure discovery and registry lookups still run. To specify paths in a directory artifact…" as a single paragraph. Add a trailing blank line before the appended .kosli_ignore block in kosli-dev/cli → cmd/kosli/snapshotAzure.go.

2 Critical, 1 Improvement, 4 upstream. The regeneration itself is faithful and should merge; the two Critical findings are pre-existing hand-authored pages that this release makes wrong, and are worth a follow-up PR before v2.40.0 is announced. Note: mint broken-links was not run (CLI not installed in this job), but the diff adds no new internal links.
· branch reference-docs/v2.40.0